Refactor: decompose Parse::parse() into ParseContext + per-state handlers - #71

Decompose the ~772-line parse() state machine into a thin switch that
dispatches to one handler per parser state, plus sub-handlers for the
heavy STATE_ADDRESS branches (CFWS, '@', '.', atext, non-atext). parse()
is now ~190 lines.

Loop control (state/subState/commentNestLevel) and the hoisted input and
config move onto ParseContext so the handlers read them without long
parameter lists; behaviour, error codes and output are unchanged. Refresh
the Psalm baseline for the state-machine narrowing false-positives that
shift when the discriminant becomes a context property (PHPStan level 8
handles the mutation across calls and stays clean).

Fold the atext and period handling back inline into handleStateAddress so
the dominant STATE_ADDRESS path makes a single method call per character
instead of two. The larger, less-frequent branches (CFWS whitespace, '@',
non-atext) stay in their own helpers.

Behaviour is unchanged (full suite still green). Under opcache+JIT the
batch-parsing benchmarks now run at or below the pre-refactor baseline.

Document the parser internals introduced by the parse() decomposition:
the character-by-character dispatch loop, the 12 states and their 7
handlers, the ParseContext object and how a fresh instance per call keeps
parse() reentrant, and the single-source-of-truth per-address reset.

State machine and dispatch loop are drawn as mermaid so they render inline
on GitHub. Complements DESIGN.md (RFC semantics) with the implementation
shape; linked from the README docs line.

…line local

Follow-up to the parse() decomposition review (PR #71).

- Mark validateLocalPart() @internal. It is protected on a non-final class,
  so its array -> ParseContext signature change is technically a subclass
  break; but it takes the parser's internal accumulator and was never a
  supported extension point (validation is customized via ParseOptions).
  Documented as such and slated to go private in v4.0 (roadmap).

- Give ParseContext a constructor requiring the initial state/subState,
  which runs resetAddress(). This makes an un-initialized context
  unrepresentable, replacing the "construct then remember to reset" pattern
  and the misleading zero-value field defaults (subState 0 = STATE_TRIM,
  not the required STATE_START).

- Inline the single-use $separators local straight onto the context.

108 tests / 7172 assertions, PHPStan and CS clean.

…mpose

# Conflicts:
#	README.md

The file had drifted into a jumbled mix of shipped and planned work with
duplicated and misfiled sections. Reorganized without dropping substance:

- Split into three clear parts: Released (v3.1-v3.8 + deprecations + docs),
  Quality & infrastructure (continuous), and Planned (v4.0 + backlog).
- Removed the duplicate v4.0 list (the Deprecation Timeline had its own
  "v4.0 - planned" subsection overlapping the real v4.0 section); merged and
  deduped the API-cleanup items into a single v4.0 section.
- Refiled the shipped 3.8.0 homoglyph feature out of "v4.0 - Breaking" into
  Released; its target-list follow-up stays under Planned.
- Compressed the now-delivered parse() decomposition to a one-line record
  linking ARCHITECTURE.md, with the four review follow-ups moved to Backlog.
- Dropped the stale proposal text ("currently 99 tests", the pre-refactor
  complexity pitch) and the trailing stray footnote.

The decomposition changed where Psalm narrows $ctx->state, so 15 baseline
suppressions no longer match any code and CI (findUnusedBaselineEntry) fails
them: 1 InvalidCast, 1 ParadoxicalCondition, 1 RedundantCondition, and 12
TypeDoesNotContainType. Regenerated with --update-baseline (69 -> 54 entries);
no new suppressions added. Psalm, PHPStan L8, CS, and 108 tests all green.

Review-driven follow-ups on the parse() decomposition.

- Add a reentrancy regression test: a localPartNormalizer that re-enters the
  same parser mid-parse. Locks in the property the whole ParseContext design
  exists for — a fresh per-call context, never on the instance — so a future
  change that stored parse state on $this would fail here.
- Mark ParseContext @internal (its ~24-field shape is not a stable API) and
  fix an orphaned docblock: resetAddress()'s description had been stranded
  above __construct() when the constructor was added.
- CHANGELOG [Unreleased]: record the internal decomposition and the
  validateLocalPart() array -> ParseContext / @internal change.
- ROADMAP: expand the refactor follow-ups with the SOTA items surfaced in
  review — readonly snapshot/config fields, a ParserState backed enum
  (benchmark-gated), and decomposing addAddress().

109 tests / 7177 assertions, PHPStan L8, Psalm, CS all green.

Makes the parse() decomposition fully backward compatible: no public or
protected signature changes vs the previous release.

validateLocalPart() reads only local_part_parsed and local_part_quoted from
the accumulator, so instead of changing its signature to ParseContext it keeps
its original array signature and is dispatched through a small legacy-array
bridge at the one call site. It stays a live (virtual) extension point — a
subclass override is still invoked — but is now @deprecated and removed in
4.0, where local-part validation folds into a private ParseContext-based
method. The supported way to customize validation remains ParseOptions.

- Added a BC regression test: a Parse subclass overriding validateLocalPart()
  still changes the outcome (rejects a 'blocked' local part).
- ParseContext stays @internal.
- One @psalm-suppress DeprecatedMethod on the intentional internal BC hook.

110 tests / 7193 assertions, PHPStan L8, Psalm, CS all green.

The v4.0 removal was already listed under Planned; add the matching entry to
the Deprecations record so "what's deprecated / when removed" is complete.